NetCloak 3.0 User's Guide: Commands: Utility

	Version 3.0 User's Guide

Commands: Utility	Previous \| Next Contents

<INSERT_BEEP>

At first glance, this command may not seen to be useful, but there are several cases in which it can be handy. The INSERT_BEEP command causes the server to play the default system alert sound whenever the command is encountered. Nothing is inserted into the text of the page being served. The only effect is a system beep on the server.

You can use INSERT_BEEP while you are developing pages with NetCloak commands to verify that NetCloak is processing the page.

Another possible use for this command is in your server's error page. By including the command INSERT_BEEP on the error page, your server will beep any time an incorrect URL is processed by your server. This can give you a warning of broken links on your site as they are happening.

<REDIRECT url>

The REDIRECT command is a little different from most other NetCloak commands. When this command is encountered in your cloaked HTML document, all processing of the page will immediately cease, and a redirect header will be sent to the browser. This causes the browser to immediately transfer to the URL specified.

Note that a REDIRECT command causes all other contents of the page to be ignored. The redirect will not cause the redirected page to appear within the text of the original page.

The command will not cause a redirect to occur if it is hidden by another NetCloak command, so redirects can be performed conditionally based on any SHOW and HIDE commands. The redirect command can be used in the server's error file to automatically send clients accessing bad URLs to the correct pages. You might also use the command to redirect an HTML page to a page that might be in a completely different format depending on the client's browser type, address or other information.

Here is an example of using REDIRECT to send a special "internal use only" page based on the user's TCP/IP address. In the example, users in the domain "192.1." will be sent to the page "Protected.html". All other users will receive the public page.

    <HIDE>    <SHOW_DOMAIN 192.1.>    <REDIRECT "http://my.server/Protected.html">    <SHOW>    <HTML>    <TITLE>Public Home Page</TITLE>    <BODY>    Welcome to our public Home Page!
    </BODY>    </HTML>

The normal REDIRECT command returns a "302 Moved Temporarily" response to the requesting browser. The REDIRECT command can also return a "301 Moved Permanently" response, by using REDIRECT* instead of REDIRECT, like this:

    <REDIRECT* "http://my.server/Protected.html">

For permanently moved files, the 301 response notifies caching mechanisms such as proxy servers and search engines that the old URL should be replaced permanently.

<REPEAT var operator value1 value2 ...>
</REPEAT>

The REPEAT command is a very powerful command that allows you to insert a chunk of HTML text into a web page a number of times, based on the value of any NetCloak global, local, user, counter, or cookie variable. The HTML to be repeated is placed between the opening <REPEAT> tag and the closing </REPEAT> tag. The number of times the text will be inserted depends on the condition defined in the REPEAT tag. The text is repeated until the condition is false. If the condition is always false, then no text is inserted.

Any comparison operator supported by the SHOW and HIDE commands may also be used in the REPEAT command. If the comparison operator is omitted, the REPEAT command will loop as long as the specified variable exists.

It is up to you to make sure an infinite loop is not created. When an infinite loop occurs, NetCloak continues to add the text to the returned page indefinitely and will makethe server freeze or crash. In order to avoid an infinite loop, you must update some loop variable between the <REPEAT> and </REPEAT> tags so that the condition in the REPEAT tag eventually becomes false.

Ordinarily, you would use SET_LOCAL commands to increment or decrement a local variable inside the REPEAT tags. For example, the following code will create a simple 2-row by 3-column table:

    <SET_LOCAL row = 1>    <SET_LOCAL col = 1>    <TABLE>    <REPEAT row LT= 2>     <TR>     <REPEAT col LT= 3>      <TD>Row <INSERT_LOCAL row> Col <INSERT_LOCAL   col></TD>      <SET_LOCAL col = col + 1>     </REPEAT>     </TR>     <SET_LOCAL row = row + 1>    </REPEAT>    </TABLE>

Here is the HTML text that is actually sent to the browser:

    <TABLE>     <TR>      <TD>Row 1 Col 1</TD>      <TD>Row 1 Col 2</TD>      <TD>Row 1 Col 3</TD>     </TR>     <TR>      <TD>Row 2 Col 1</TD>      <TD>Row 2 Col 2</TD>      <TD>Row 2 Col 3</TD>     </TR>    </TABLE>

The variable in the REPEAT command may also be a multivalue form variable (such as a group of checkboxes or a multi-select list box). In that case, you use a local variable to access each instance of the multivalue variable. For instance, let's suppose a user has filled out a form which contains a set of checkboxes to pick pizza toppings. You want to display the selected toppings back to the user so they can confirm their order. The checkboxes are all named "Topping", and each checkbox in the form has a different value, like this:

    <INPUT TYPE="checkbox" NAME="Topping"    VALUE="sausage">    <INPUT TYPE="checkbox" NAME="Topping"    VALUE="pepperoni">    <INPUT TYPE="checkbox" NAME="Topping"    VALUE="mushrooms">

If the user chooses more than one topping, then multiple instances of the variable "Topping" will be created by NetCloak. Each instance can be accessed using square brackets like this: "Topping [1]", "Topping[2]", etc.

To loop through all the selected toppings, you can use a local variable between the square brackets, and repeat as long as an instance of the multivalue variable exists. So here is an excerpt from the order confirmation page:

    <P>Selected Toppings: 
    <SET_LOCAL index = 1>    <REPEAT Topping[index] EXISTS>    <INSERT_VARIABLE Topping[index]> 
    <SET_LOCAL index = index + 1>    </REPEAT>

If the user checks the "pepperoni" and "mushrooms" checkboxes in the form, the confirmation page they get looks like this:

    <P>Selected Toppings: pepperoni mushrooms

<EXEC_CGI CGIpath scriptName beginText endText>

This command allows you to dynamically execute CGIs and insert their response into a page, as well as execute multiple CGIs from a single client request. These can be either other commercial CGIs, or CGIs that you write yourself. For more information on how NetCloak calls other CGIs, see the section "Using NetCloak With Other CGIs" earlier in this User's Guide.

The EXEC_CGI command accepts up to four parameters, though the second, third and fourth are optional. The "CGIpath" parameter is simply the path to the CGI application you would like to execute. The path must be the path to the actual application , not an alias or a document created by or for the application that will be run.

The "scriptName" parameter allows you to overwrite the direct parameter sent to the CGI. Leaving this parameter blank will simply pass along the direct parameter as it originally came from the server, but overwriting this is an important capability. By changing the parameter, you can make the CGI think that the requested URL was different than it really was. This parameter also replaces the Script Name field of the CGI AppleEvent, so that CGIs that function as actions will work properly.

The filepath and scriptName parameters may be either relative to the Root Folder, or relative to the location of the page being served. They may be specified using either the URL style for file paths (using slash '/' characters to delimit folder names), or the MacOS style (using colons ':' to delimit folder names). If the first character of the file path is a colon or a slash, the file path is assumed to be relative to the Root Folder. Otherwise, it is assumed to be relative to the location of the page being served. (See the INSERT_MODIFIED command for more information about filepath parameters.)

Maxum has produced a simple, freeware CGI named "Responder" which is useful for testing or demonstrating the EXEC_CGI command. Responder simply echoes the CGI request that is sent to it as an HTML page listing the various parameters separately. Here is a snippet that will include Responder's output in an HTML page served by NetCloak:

    <EXEC_CGI "Responder.cgi">

You can download Responder from the Maxum Web site at "http://www.maxum.com/".

In many cases, you may want only a portion of the CGI response. In the case of Responder, you might want only the BODY of the complete HTML page that it returns. You can filter out what you don't want by specifying a beginning and an ending phrase. Only text that appears between the phrases will then be inserted into the response page. Notice that you must specify the "scriptName" parameter (even if it is left blank) in order to use the filtering parameters. For example:

    <EXEC_CGI "Responder.cgi" "" "<BODY>" "</BODY>">

This example would include only the parts of Responder's response that are between, but not including, the <BODY> and </BODY> tags.

Note that the EXEC_CGI command does not allow setting query or post arguments. (Query arguments are included in a CGI request URL preceded by a question mark; post arguments are sent as data from an HTML form.) EXEC_CGI therefore cannot be used with CGIs that depend on these for input. This typically includes database access CGIs, as well as search tools such as Phantom. If you have a CGI that depends on query or post arguments, consider running it as a back-end to NetCloak instead.

<EXEC_PIXO serviceName scriptName startText endText>

This command is only available in the NetCloak plug-in. It operates almost identically to the EXEC_CGI command. But instead of calling an external CGI application via AppleEvents, it calls another WebSTAR API plug-in running on the same Web server as NetCloak, using the PIXO ("Plug-In Cross-Over") standard for inter-plug-in communication jointly developed by Maxum and Clearway Technologies, Inc. Most commercial WebSTAR plug-ins available today support PIXO.

The first parameter, "serviceName", is the name of the PIXO service registered by the plug-in you want to call. The PIXO standard requires plug-ins to register a "service name" which provides other plug-ins access to their functionality. The convention for naming a PIXO service is to append the text "_PIXO" to the plug-in's normal action name. For instance, NetCloak's PIXO service name for processing HTML pages is "CLOAK_PI_PIXO", and the PIXO service name used by NetCloak Pro to process FDML files is "NFORMS_PI_PIXO".

Included in the NetCloak package (in the "Goodies" folder) is a plug-in called "FireSite SSI_PIXO Adapter" which allows you to call the WebSTAR SSI plug-in from cloaked pages. When this plug-in, WebSTAR SSI, and NetCloak are all installed, you can insert the contents of an SSI-processed page into a NetCloak-processed page like this:

    <EXEC_PIXO "SSI_PIXO" "ssipage.shtml" "<BODY>" "</BODY>">

The above command will call WebSTAR SSI to process the file "ssipage.shtml", and then insert the text between the <BODY> and </BODY> tags into the current page.

<MACRO macroName>

The Macro command is used to insert text or HTML from a local file or predefined macros. If the specified macro name matches the name of a macro defined in the file "NetCloak.macros", NetCloak will insert the contents of that macro into the HTML in place of the MACRO command. If the macro name is a pathname for a file, NetCloak will insert the contents of the specified file.

When inserting a file, the macroName parameter may be either relative to the Root Folder, or relative to the location of the page being served. It may be specified using either the URL style for file paths (using slash '/' characters to delimit folder names), or the MacOS style (using colons ':' to delimit folder names). If the first character of the file path is a colon or a slash, the file path is assumed to be relative to the Root Folder. Otherwise, it is assumed to be relative to the location of the page being served. (See the INSERT_MODIFIED command for more information about filepath parameters.)

When serving multiple virtual domains, macro file paths are resolved relative to the root folder for each virtual domain. This has two implications. First, no macro may access any file outside its virtual domain's root folder, unless you create aliases within the virtual domain's root folder. Second, this lets you provide macros that are customized for each virtual domain.

If NetCloak is unable to insert a specified macro, it will insert an error message enclosed in an HTML comment. View the HTML source of the document after it is served to a Web browser to see the error message.

If the specified macro contains NetCloak SHOW or HIDE commands, the show/hide state (or "mode") of text following the MACRO command is not affected by the final mode of the macro. In other words, the mode of a MACRO command is not propagated back to the calling page.

When processing a page, NetCloak does not process MACRO commands that are hidden by a previous HIDE command.

A trivial example will help explain this. Consider the following macro, defined in the "NetCloak.macros" file:

    <BEGIN_MACRO TurnOn>    <SHOW>    <END_MACRO>

This macro does nothing when used in a cloaked page:

    <HIDE>    This text is hidden from all users all the time.
    <MACRO TurnOn>    This text is ALSO always hidden! In fact, NetCloak won't even call the  macro.
    <SHOW>

If you want a macro to affect the mode of the calling page, use the MODEMACRO command (see below) instead.

<MODEMACRO macroName>

MODEMACRO behaves identically to the MACRO command, except for two important differences:

The show/hide mode of text following a MODEMACRO command matches the final show/hide mode inside the called macro.
MODEMACRO commands cannot be hidden by a HIDE command. They are always processed wherever they occur in a cloaked page.

Using the same example "TurnOn" macro defined above, the following code works as expected:

    <HIDE>    This text is hidden from all users all the time.
    <MODEMACRO TurnOn>    This text is shown to all users.

See the Macros section, next, for more information on defining and using macros.


Copyright © 1996-1999 Maxum Development Corporation http://www.maxum.com/	Previous \| Next Contents

Commands: Utility